home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / golded / api / readme < prev    next >
Text File  |  1994-08-12  |  7KB  |  122 lines
  1.                            API - Application Interface
  2. English ..... A-1
  3. Deutsch ..... A-2
  4. Français .... A-3
  5.                                    A-1 English
  6. BASICS
  7.  
  8. GoldED offers a message-based application interface (API). This interface may be
  9. used  by  third  party  applications  to  register  with  GoldED:  after  having
  10. registered by sending the API command to GoldED's ARexx port they  will  recieve
  11. notify  messages  from  GoldED.  Depending  on  these  messages  they  can  take
  12. approbiate actions (e.g. close their windows  if  GED  is  about  to  close  its
  13. screen,  indicating  this  by sending API_ACTION_HIDE messages to all registered
  14. clients).
  15.  
  16. HOW TO RUN CLIENTS
  17.  
  18. Clients are launched during startup of GoldED (use the API list  of  the  config
  19. menu  if you want to add or remove clients). The name of GoldED's port is passed
  20. as HOST=... argument. The client is expected to register with GED by sending the
  21. API  command  to  this  port,  thus  providing a port for notifys and requesting
  22. notify classes (clients may select a subset of the available notifys).
  23.  
  24. Shortly after the API client has registered  with  GoldED  it  will  recieve  an
  25. API_ACTION_SHOW  notify  of  the  API_CLASS_SCREEN  class  (if  the  client  has
  26. requested API_CLASS_SCREEN events), telling the client to open its windows. This
  27. notify  (and  any  other  notify)  includes  a variety of informations about the
  28. editor's current state (including text of current line,  window  dimensions  and
  29. screen name).
  30.  
  31. RESTRICTIONS
  32.  
  33. After a client has registered with GoldED it has to be able  to  answer  notifys
  34. immediately  until  the API_ACTION_DIE command is recieved (the user has to WAIT
  35. for your client to complete processing). To avoid deadlock problems, you may not
  36. wait  for  completion  of  ARexx  requests  sent  to  GED using WaitPort() (thus
  37. ignoring incoming API messages). Use Wait() instead.
  38.  
  39.  
  40.                                    A-2 Deutsch
  41. Grundlagen
  42.  
  43. GoldED bietet externen Programmen mit dem API-Interface eine  Möglichkeit,  sich
  44. in  die  internen  Abläufe  des  Editors  einzuklinken. Ein Programm, das dieses
  45. Interface benutzt, wird im folgenden als Client  bezeichnet.  Das  API-Interface
  46. baut  wie  auch  ARexx auf Messages auf. Im Gegensatz zu ARexx geht die Richtung
  47. des Informationsflusses aber primär von GoldED zu den externen  Programmen:  der
  48. Ablauf  wird durch den Editor gesteuert. Grundsätzlich kann man sich Clients wie
  49. Unterprogramme des  Editors  vorstellen:  sie  werden  vom  Editor  "aktiviert",
  50. übernehmen   die   Ausführung   und   geben  i.d.R.  ein  Ergebnis  zurück.  Die
  51. Client-Einbindung erfolgt, indem sich dieser bei GoldED mit dem ARexxBefehl  API
  52. anmeldet.  Dabei  hat  er  mitzuteilen,  in  welchen Situationen er "aufgerufen"
  53. werden möchte und an welchem Port GoldED die entsprechende Nachricht hinterlegen
  54. soll.  Tritt  eine  der  ausgewählten  Situationen  auf,  schickt  GoldED an den
  55. angegebenen Port eine Message (Notify), die nähere Informationen (vgl. golded.h)
  56. enthält.  Der  Client  wird  diese  Nachricht  untersuchen,  geeignete  Aktionen
  57. durchführen und dann die Nachricht beantworten. Erst mit der Beantwortung  fährt
  58. GoldED  in  seinem  Programmablauf  fort.  Die Art der Antwort kann den weiteren
  59. Programmablauf beeinflussen.
  60.  
  61. Wie werden Clients gestartet ?
  62.  
  63. Benutzen Sie den API-Requester, um Clients auszuwählen. Jedes dort  eingetragene
  64. Programm  wird  im Zuge des Editor-Startups aufgerufen. Der Name des ARexx-Ports
  65. von GED wird dem Client als (letztes) Argument HOST=...  übergeben.  Der  Client
  66. bekommt  so  die  Möglichkeit,  sich  über ARexx beim Editor anzumelden. Mit dem
  67. API-Kommando teilt er dem Editor  mit,  in  welchen  Situationen  er  informiert
  68. werden  soll  und  an  welchen  Message-Port die Informationen verschickt werden
  69. sollen. Kurz nachdem sich der Client angemeldet hat, erhält er von  GoldED  eine
  70. erste  API_ACTION_SHOW-Benachrichtigung  (sofern  der  Client  Informationen der
  71. API_CLASS_SCREEN angefordert hat): dies ist sein  Signal,  die  eigenen  Fenster
  72. (sofern   vorgesehen)  zu  öffnen.  Dazu  benötigte  Informationen  wie  der  zu
  73. benutzende Screen kann er der Benachrichtigung entnehmen.
  74.  
  75. Einschränkungen
  76.  
  77. Nachdem sich ein Client über den API-Befehl erfolgreich beim  Editor  angemeldet
  78. hat,   muss  er  in  der  Lage  sein,  eingehende  Nachrichten  unverzüglich  zu
  79. bearbeiten, bis er eine API_ACTION_DIE-Benachrichtigung erhält. Wenn GoldED  auf
  80. einen   Client   wartet,  dann  wartet  auch  der  Anwender/die  Anwenderin.  Um
  81. DeadLock-Probleme zu vermeiden,  darf  niemals  per  WaitPort()  auf  abgesandte
  82. ARexx-Requests  gewartet  werden  (GED  könnte auf eine API-Reaktion des Clients
  83. warten, der Client wartet auf GoldED: das System ist blockiert).  Verwenden  Sie
  84. ersatzweise Wait().
  85.  
  86.                                    A-3 Français
  87.  
  88. FONDEMENTS
  89.  
  90. GoldED propose un interface  application  (API),  basé  sur  les  messages.  Cet
  91. interface  peut  être utilisée par des applications pour s'enregistrer à GoldED:
  92. après s'être enregistrées en envoyant la commande API au port ARexx  de  GoldED,
  93. celles-ci  recevront les messages de notification de GoldED. Selon ces messages,
  94. ces applications peuvent alors accomplir les actions  appropriées  (par  exemple
  95. fermer leurs fenêtres si GED va fermer son écran, indiquant cela en envoyant les
  96. messages API_ACTION_HIDE à tous ses clients enregistrés).
  97.  
  98. COMMENT DEMARRER DES CLIENTS
  99.  
  100. Les clients sont lancés lors du démarrage de GoldED (utilisez la  liste  API  du
  101. menu  Config  si  vous voulez ajouter ou retirer des clients). Le nom du port de
  102. GoldED est passé comme argument <HOST=...>. Le client doit s'enregistrer  à  GED
  103. en  envoyant  la  commande  API  à  ce  port,  fournir  en plus un port pour les
  104. notifications et demander les classes  de  notifications  (les  clients  peuvent
  105. sélectionner une partie des notifications disponibles).
  106.  
  107. Dès  que  le  client  API  a  été  enregistré  à  GoldED,  celui-ci  reçoit  une
  108. notification  API_ACTION_SHOW  de  la  classe  API_CLASS_SCREEN  (si le client a
  109. demandé les événements API_CLASS_SCREEN),  lui  disant  d'ouvrir  ses  fenêtres.
  110. Cette  notification  (et  toutes  les  autres notifications) inclut une quantité
  111. d'informations sur l'état actuel de l'éditeur (incluant le texte  sur  la  ligne
  112. actuelle, les dimensions de la fenêtre et le nom de l'écran).
  113.  
  114. RESTRICTIONS
  115.  
  116. Dès qu'un client a été enregistré  à  GoldED,  celui-ci  doit  être  capable  de
  117. répondre   immédiatement   aux   notifications   jusqu'à   ce  que  la  commande
  118. API_ACTION_DIE soit reçue (l'utilisateur devra ATTENDRE la fin du traitement par
  119. le  client).  Pour  éviter des problèmes de temps mort (deadlock), vous ne devez
  120. pas attendre la fin des requêtes ARexx envoyées à GED  en  utilisant  WaitPort()
  121. (en ignorant en plus les messages API arrivants). Utilisez Wait() à la place.
  122.